Conversation
There was a problem hiding this comment.
Pull request overview
Adds in-repo documentation (in the “ripgrep-style” pattern) to help users understand common sslx workflows and answer common comparison/safety questions.
Changes:
- Add
GUIDE.mdcovering key CLI workflows (connect/grade/expiry, file operations, JSON output, completions). - Add
FAQ.mdexplaining howsslxcompares to other tools and how it’s intended to be used.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| GUIDE.md | New end-to-end usage guide with examples, JSON snippets, and operational tips (cron/CI). |
| FAQ.md | New FAQ clarifying positioning vs openssl/step-cli/mkcert and addressing CI/safety concerns. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| openssl is a cryptographic library with a CLI bolted on. It does everything (TLS, symmetric crypto, PKCS, ASN.1, etc) but the CLI syntax is inconsistent and hard to remember. | ||
|
|
||
| sslx only does certificate and TLS operations. It's a single binary with consistent flags, colored output, and commands you can actually remember. |
There was a problem hiding this comment.
This section says “sslx only does certificate and TLS operations”, but the very next paragraph lists JWT decoding as a feature. Consider rephrasing to something like “focused on TLS/cert workflows (plus a few related helpers like JWT decoding)” to avoid a self-contradiction.
| sslx only does certificate and TLS operations. It's a single binary with consistent flags, colored output, and commands you can actually remember. | |
| sslx is focused on certificate and TLS workflows, plus a few related helpers. It's a single binary with consistent flags, colored output, and commands you can actually remember. |
|
|
||
| ## Does sslx use OpenSSL? | ||
|
|
||
| No. sslx is built with rustls, a TLS library written in Rust. There's no dependency on system OpenSSL at all. The binary is fully static and works the same everywhere. |
There was a problem hiding this comment.
The claim that “The binary is fully static” doesn’t match the current release configuration: the GitHub Actions release workflow builds *-unknown-linux-gnu and *-apple-darwin targets, which are typically dynamically linked (and not “fully static” across platforms). Suggest removing “fully static” or qualifying it to specific release artifacts/targets if you actually ship static builds.
| No. sslx is built with rustls, a TLS library written in Rust. There's no dependency on system OpenSSL at all. The binary is fully static and works the same everywhere. | |
| No. sslx is built with rustls, a TLS library written in Rust. There's no dependency on system OpenSSL at all, and sslx behaves consistently across supported platforms. |
| | Code | Meaning | | ||
| |------|---------| | ||
| | 0 | ok | | ||
| | 1 | cert expired or expiring soon | | ||
| | 3 | chain untrusted or incomplete | |
There was a problem hiding this comment.
The exit-codes table isn’t valid Markdown: the header/rows start with || instead of |, which typically won’t render as a table. Replace the leading || with a single | on each row (and keep the separator row consistent).
| | 1 | cert expired or expiring soon | | ||
| | 3 | chain untrusted or incomplete | | ||
| | 4 | connection failed | | ||
| | 5 | file format error | | ||
| | 10 | bad arguments | | ||
|
|
||
| These work with set -e in shell scripts and CI pipelines. | ||
|
|
There was a problem hiding this comment.
This table documents global meanings for exit codes that don’t match the current implementation. For example, code 4 is never returned (connection failures bubble up as an error and main exits with 10), and code 5 is only used by decode when it can’t detect a format (most other “bad file/format” cases also exit 10). Consider either updating the docs to reflect per-command exit codes, or updating the CLI to consistently use the documented codes.
| | 1 | cert expired or expiring soon | | |
| | 3 | chain untrusted or incomplete | | |
| | 4 | connection failed | | |
| | 5 | file format error | | |
| | 10 | bad arguments | | |
| These work with set -e in shell scripts and CI pipelines. | |
| | 10 | bad arguments / invalid usage | | |
| Some commands may return other non-zero exit codes for command-specific conditions, but those codes are not consistent across all commands. | |
| If you need command-level behavior, check `sslx <command> --help` and test that command directly in scripts. | |
| These work with `set -e` in shell scripts and CI pipelines. |
| Exit code is 1 if any cert expires within 7 days. Put this in a cron job: | ||
|
|
||
| ```bash | ||
| # check every morning at 8am | ||
| 0 8 * * * /usr/local/bin/sslx expiry prod.example.com api.example.com || notify-send "cert expiring" |
There was a problem hiding this comment.
sslx expiry also exits with code 1 when a host check errors (e.g., DNS/timeout/TLS handshake failure), not only when a cert expires within 7 days (see src/commands/expiry.rs, which sets any_critical = true on Err). Consider mentioning the error case here so CI/cron usage is less surprising.
| Exit code is 1 if any cert expires within 7 days. Put this in a cron job: | |
| ```bash | |
| # check every morning at 8am | |
| 0 8 * * * /usr/local/bin/sslx expiry prod.example.com api.example.com || notify-send "cert expiring" | |
| Exit code is 1 if any cert expires within 7 days, or if a host check errors (for example DNS, timeout, or TLS handshake failures). Put this in a cron job: | |
| ```bash | |
| # check every morning at 8am | |
| 0 8 * * * /usr/local/bin/sslx expiry prod.example.com api.example.com || notify-send "cert expiring or host check failed" |
adds GUIDE.md and FAQ.md following the ripgrep pattern for in-repo docs.